# 🏠 HouseHive: Smart Rental Platform - Complete Requirements Document

## 📋 Project Overview

**HouseHive** is a modern, intuitive rental platform connecting house owners and tenants in Tier 2/3 cities across India. The platform emphasizes transparency, verified listings, and location-based discovery with an Apple-inspired design system that prioritizes simplicity and elegance.

> 💡 **Vision Statement**: "Making house hunting as seamless as checking your favorite social media app, with the trust of verified listings and the convenience of WhatsApp integration."

```mermaid
flowchart LR
    A[Guest User] --> B[Browse Properties]
    B --> C[Create Account]
    C --> D{Choose Role}
    D -->|House Owner| E[Post Property]
    D -->|Tenant| F[Request Visit]
    E --> G[Get Verified Badge]
    F --> H[Contact via WhatsApp]
    G --> I[Premium Visibility]
    H --> J[Schedule Visit]
    J --> K[Close Deal]
```

## 🎯 1. User Roles & Access Levels

### 🏠 House Owner
- **Primary Goal**: List properties, manage inquiries, communicate with tenants
- **Access Level**: Property management, messaging, analytics
- **Key Features**:
  - Property listing creation & management
  - Photo/video upload
  - Inquiry handling
  - Visit scheduling
  - Rental applications
  - Payment tracking
  - Analytics dashboard

### 👤 Tenant
- **Primary Goal**: Find suitable properties, schedule visits, communicate with owners
- **Access Level**: Search, save properties, request visits
- **Key Features**:
  - Advanced property search
  - Save favorite properties
  - Request property visits
  - Direct messaging with owners
  - Rental applications
  - Document management

### ⚙️ Admin
- **Primary Goal**: Platform management, user support, content moderation
- **Access Level**: Full system access
- **Key Features**:
  - User management
  - Property verification
  - Content moderation
  - Analytics & reporting
  - Payment processing
  - System configuration

## 🏗️ 2. Core Feature Requirements

### 📱 Property Discovery & Search

<details>
<summary>🔍 Advanced Search & Filtering</summary>

**Basic Filters**:
- Location (map-based or text search)
- Rent range (slider with min/max)
- Property type (apartment, house, PG, etc.)
- Number of bedrooms/bathrooms
- Furnishing status
- Property size
- Available date
- Amenities (AC, Parking, Lift, etc.)

**Advanced Filters**:
- Verified listings only
- Premium listings only
- Pet-friendly properties
- Family/Bachelor preferences
- Floor preference
- Parking type (covered/open)
- Water supply
- Power backup
- Security features

**Smart Matching Algorithm**:
- Budget compatibility
- Location proximity
- Amenity matching
- Move-in date alignment
- Lifestyle preferences

**Map-Based Exploration**:
- Interactive map with property markers
- Clustered view for dense areas
- Radius search from specific point
- Neighborhood information overlay
- Transit connectivity markers
- Price heat map by area
</details>

### 🏠 Property Listing Management

<details>
<summary>📊 Owner Property Dashboard</summary>

**Listing Creation Flow**:
1. **Basic Information**:
   - Property type & configuration
   - Address & location pin on map
   - Rent & security deposit
   - Available date
   - Property age & condition

2. **Detailed Specifications**:
   - Number of rooms & sizes
   - Furnishing details
   - Amenities checklist
   - Parking details
   - Floor & total floors
   - Facing direction
   - Water supply hours
   - Power backup availability

3. **Media Upload**:
   - High-quality photos (minimum 5, maximum 20)
   - Virtual tour video (optional)
   - Floor plan upload
   - 360° panorama photos (optional)

4. **Verification Process**:
   - Document verification
   - Physical visit scheduling
   - Property inspection checklist
   - Owner verification
   - Badge assignment upon completion

**Property Management Features**:
- Status management (active/inactive/rented)
- Inquiry inbox
- Visit request management
- Document management
- Rental agreement templates
- Payment reminders
- Review responses
</details>

### 💬 Communication & Interaction

<details>
<summary>📱 Contact & Messaging System</summary>

**WhatsApp Integration**:
- Hidden contact number until interest shown
- "Show Interest" button reveals contact
- Pre-filled WhatsApp message with property details
- Direct call option
- Email fallback option

**In-App Messaging**:
- Real-time chat between parties
- Message history
- File sharing (documents, photos)
- Visit scheduling integration
- Notification system

**Visit Request System**:
- Calendar-based scheduling
- Time slot selection
- Reminder notifications
- Rescheduling options
- Visit notes & feedback
</details>

### 🗺️ Map Integration & Location Services

<details>
<summary>📍 Advanced Mapping Features</summary>

**Map Display Components**:
- **Property Markers**:
  - Custom house-shaped icons
  - Color coding by price range
  - Price display on hover
  - Clustered view for zoomed-out areas

- **Neighborhood Information**:
  - Nearby schools, hospitals, markets
  - Public transit stops
  - Parks & recreational areas
  - Distance to key locations
  - Walking time estimates

**Location Features**:
- Precise location pinning (draggable)
- Address autocomplete
- Area boundaries visualization
- Transit route overlays
- Street view integration
</details>

### ✅ Verification & Trust System

<details>
<summary>🛡️ Property Verification Process</summary>

**Verification Levels**:
1. **Basic Verification**:
   - Document verification
   - Phone number verification
   - Email verification

2. **Standard Verification** (Paid):
   - Physical property visit
   - Photo verification
   - Owner identity verification
   - Address confirmation

3. **Premium Verification**:
   - Video verification call
   - Enhanced listing placement
   - Verified badge with animation
   - Priority in search results
   - Featured in weekly digest

**Verification Workflow**:
1. Owner requests verification
2. Admin schedules visit
3. Physical inspection & photo capture
4. Document cross-verification
5. Badge assignment with unique ID
6. Periodic re-verification
</details>

### 🔐 User Management & Authentication

<details>
<summary>👤 User Account Features</summary>

**Registration & Login**:
- Email/phone registration
- Social media login (Google, Facebook)
- OTP verification
- Password recovery
- Two-factor authentication (optional)

**Profile Management**:
- Profile photo
- Contact information
- Preferences storage
- Search history
- Saved properties
- Visit history
- Application history
</details>

## 🎨 3. Design Requirements & User Experience

### 📐 Apple-Inspired Design System

**Visual Language**:
- **Clean, minimal interface** with ample whitespace
- **Typography hierarchy** with clear visual cues
- **Color palette**: 
  - Primary: #007AFF (Blue)
  - Secondary: #34C759 (Green)
  - Accent: #FF9500 (Orange)
  - Background: #F5F5F7 (Light Gray)
  - Text: #1D1D1F (Black)

**Design Principles**:
1. **Clarity**: Text legible at every size
2. **Deference**: Content first, chrome second
3. **Depth**: Subtle visual transitions

**Component Library**:
- SF Pro font family (or similar system fonts)
- Custom iconography with consistent stroke weights
- Rounded corners (8px radius standard)
- Subtle shadows and depth effects
- Smooth animations and transitions

### ✨ Interactive Elements & Animations

<details>
<summary>🎬 Micro-interactions & Animations</summary>

**Loading States**:
- Skeleton screens during data loading
- Progress indicators for uploads
- Animated map loading
- Smooth transitions between views

**Interactive Components**:
- **Map Interactions**:
  - Smooth zoom & pan
  - Marker animations on hover
  - Info window slide-ins
  - Cluster expansion animations

- **Card Interactions**:
  - 3D hover effects
  - Image carousels with gesture support
  - Expandable sections
  - Swipe actions for mobile

- **Form Interactions**:
  - Real-time validation feedback
  - Animated input labels
  - Progress indicators for multi-step forms
  - Success/failure animations

**Page Transitions**:
- Fade-in content on page load
- Slide-in modals and panels
- Animated navigation between sections
- Smooth scrolling with parallax effects
</details>

### 📱 Responsive Design Requirements

**Breakpoints**:
- Mobile: 320-768px (primary focus)
- Tablet: 768-1024px
- Desktop: 1024px+

**Mobile-Specific Features**:
- Bottom navigation bar
- Touch-optimized gestures
- Swipe-to-reveal actions
- Native-like scroll behaviors
- Optimized image loading

## 🏗️ 4. Technical Requirements (Client Perspective)

### 🖥️ Backend System Requirements

**Core Functionality**:
- User authentication & authorization
- Property CRUD operations
- Image/video processing
- Search & filtering algorithms
- Messaging system
- Notification services
- Payment integration
- Analytics tracking
- API for mobile apps (future)

**Performance Requirements**:
- Page load < 3 seconds
- Search results < 1 second
- Image optimization
- Database query optimization
- Caching strategies
- CDN for media delivery

### 🔧 Third-Party Integrations

| Service | Purpose | Priority |
|---------|---------|----------|
| Google Maps API | Location services, map display | High |
| WhatsApp Business API | Contact integration | High |
| Payment Gateway | Verified listing payments | Medium |
| SMS Gateway | OTP notifications | Medium |
| Email Service | Transactional emails | High |
| Analytics | User behavior tracking | Medium |

### 📊 Data Management

**Property Data Structure**:
- Basic information
- Detailed specifications
- Media files
- Location data
- Verification status
- Owner information
- Availability calendar

**User Data Structure**:
- Authentication credentials
- Profile information
- Preferences
- Activity history
- Saved properties
- Applications

## 🚀 5. Development Approach & Methodology

### 📅 Project Timeline

```mermaid
timeline
    title HouseHive Development Timeline
    section Phase 1 (Weeks 1-4)
        Requirements & Design : UI/UX Design : Core Backend Setup
    section Phase 2 (Weeks 5-8)
        Property Management : Search & Filtering : Basic Map Integration
    section Phase 3 (Weeks 9-12)
        User Authentication : Messaging System : WhatsApp Integration
    section Phase 4 (Weeks 13-16)
        Verification System : Admin Dashboard : Payment Integration
    section Phase 5 (Weeks 17-20)
        Testing & Optimization : Launch Preparation : Deployment
```

### 🎯 Development Methodology

**Approach**:
- **Agile development** with 2-week sprints
- **Client involvement** in every phase
- **Iterative feedback** loops
- **Continuous testing** throughout development

**Quality Assurance**:
- **Automated testing** for critical functionality
- **Cross-browser testing**
- **Mobile device testing**
- **Performance testing**
- **Security audits**

### 🔄 Maintenance & Support

**Post-Launch Support**:
- **Bug fixing** and updates
- **Performance monitoring**
- **Security patches**
- **Feature enhancements**
- **User feedback incorporation**

## ✅ 6. Complete Requirements Checklist

### 📋 Core Features

- [ ] **User Authentication System**
  - [ ] Email/password registration
  - [ ] Social media login
  - [ ] OTP verification
  - [ ] Password recovery
  - [ ] Role-based access control

- [ ] **Property Management**
  - [ ] Property listing creation
  - [ ] Multi-step listing wizard
  - [ ] Media upload (photos, videos)
  - [ ] Property status management
  - [ ] Rental application handling

- [ ] **Search & Discovery**
  - [ ] Advanced filtering system
  - [ ] Map-based exploration
  - [ ] Location-based search
  - [ ] Saved searches
  - [ ] Similar property suggestions

- [ ] **Communication Tools**
  - [ ] In-app messaging
  - [ ] WhatsApp integration
  - [ ] Visit scheduling
  - [ ] Notification system
  - [ ] Email alerts

- [ ] **Verification System**
  - [ ] Document verification
  - [ ] Physical verification process
  - [ ] Badge assignment
  - [ ] Verification tracking
  - [ ] Re-verification scheduling

### 🎨 Design & User Experience

- [ ] **Apple-inspired Design System**
  - [ ] Consistent visual language
  - [ ] Typography hierarchy
  - [ ] Color palette implementation
  - [ ] Component library
  - [ ] Animation library

- [ ] **Responsive Design**
  - [ ] Mobile-first approach
  - [ ] Tablet optimization
  - [ ] Desktop experience
  - [ ] Touch-optimized interactions
  - [ ] Cross-browser compatibility

- [ ] **Interactive Elements**
  - [ ] Micro-interactions
  - [ ] Loading animations
  - [ ] Page transitions
  - [ ] Form feedback
  - [ ] Map interactions

### 🔧 Technical Implementation

- [ ] **Backend Architecture**
  - [ ] Laravel framework setup
  - [ ] Database design
  - [ ] API development
  - [ ] Authentication system
  - [ ] File storage management

- [ ] **Third-party Integrations**
  - [ ] Google Maps integration
  - [ ] WhatsApp Business API
  - [ ] Payment gateway
  - [ ] SMS/Email services
  - [ ] Analytics integration

- [ ] **Performance Optimization**
  - [ ] Image optimization
  - [ ] Database indexing
  - [ ] Caching implementation
  - [ ] CDN configuration
  - [ ] Query optimization

### 📊 Analytics & Reporting

- [ ] **User Analytics**
  - [ ] User behavior tracking
  - [ ] Conversion funnels
  - [ ] Feature usage statistics
  - [ ] Geographic distribution
  - [ ] Device analytics

- [ ] **Business Analytics**
  - [ ] Property performance
  - [ ] Owner engagement
  - [ ] Tenant activity
  - [ ] Revenue tracking
  - [ ] Market trends

## 🎯 7. Success Metrics & KPIs

### 📈 Key Performance Indicators

| Metric | Target | Measurement Method |
|--------|--------|-------------------|
| **User Engagement** | > 5 minutes average session | Analytics tracking |
| **Property Views** | > 1000 views per week | Platform analytics |
| **Conversion Rate** | > 2% visit requests to deals | CRM tracking |
| **User Retention** | > 40% monthly active users | Cohort analysis |
| **Verified Listings** | > 30% of total listings | Database query |
| **Response Time** | < 24 hours for inquiries | Messaging system |

### 🏆 Business Goals

1. **User Acquisition**: 10,000 registered users in first 6 months
2. **Property Listings**: 5,000 active listings across Tier 2/3 cities
3. **Revenue Generation**: Verified listing premium subscriptions
4. **Market Penetration**: 5 cities in first year, 15 by end of second year
5. **User Satisfaction**: > 4.5/5 rating on app stores

## 📝 8. Additional Requirements & Considerations

### 🔒 Security Requirements

- **Data Protection**: GDPR compliance, data encryption
- **Payment Security**: PCI compliance for payment processing
- **User Privacy**: Clear privacy policy, data deletion options
- **Fraud Prevention**: Verification processes, suspicious activity monitoring
- **Backup Systems**: Regular data backups, disaster recovery plan

### 🌐 Localization & Accessibility

- **Multi-language Support**: English, Hindi, regional languages
- **Accessibility Compliance**: WCAG 2.1 standards
- **Cultural Adaptation**: Local customs and preferences
- **Regional Pricing**: Currency and payment method adaptations

### 🔄 Future Enhancements

<details>
<summary>🚀 Phase 2 Features</summary>

- **AI-powered Recommendations**: Machine learning for property suggestions
- **Virtual Reality Tours**: 360° property viewing
- **Smart Contracts**: Blockchain-based rental agreements
- **IoT Integration**: Smart home device compatibility
- **Community Features**: Neighborhood forums and reviews
</details>

## 🎨 9. Design Mockup Descriptions

### 🏠 Landing Page Layout

**Hero Section**:
- Full-screen search bar with autocomplete
- Popular city suggestions
- Featured properties carousel
- Value proposition badges

**Property Grid**:
- Card-based layout with hover effects
- Filter sidebar (collapsible on mobile)
- Sort options dropdown
- Pagination or infinite scroll

**Map View Toggle**:
- Split-screen view (list/map)
- Full-screen map option
- Property markers with info windows
- Clustered markers for dense areas

### 📱 Mobile Experience

**Bottom Navigation**:
- Home (property feed)
- Map (exploration)
- Saved (favorites)
- Messages (chat)
- Profile (account)

**Property Cards**:
- Swipeable image galleries
- Quick action buttons (save, share, contact)
- Expandable details sections
- Floating action button for new search

## 🚀 10. Launch Strategy & Deployment

### 📦 Deployment Plan

**Infrastructure Requirements**:
- Cloud hosting with auto-scaling
- CDN for global content delivery
- Database replication for reliability
- Backup and disaster recovery systems
- Monitoring and alerting setup

**Launch Sequence**:
1. **Soft Launch**: Beta testing with limited users
2. **Marketing Campaign**: Targeted ads in Tier 2/3 cities
3. **Partnership Development**: Local real estate agents
4. **Community Building**: Early adopter programs
5. **Full Launch**: Public availability

### 📊 Success Measurement

**Post-Launch Evaluation**:
- User feedback analysis
- Performance metrics review
- Feature usage assessment
- Revenue tracking
- Market penetration analysis

---

> 🎯 **Final Note**: This requirements document serves as the complete guide for developing HouseHive - a modern, user-friendly rental platform that combines the trust of verified listings with the convenience of modern technology. The success of this project relies on maintaining the Apple-inspired design philosophy while delivering robust functionality that serves both house owners and tenants effectively in Tier 2/3 cities.

**Document Version**: 1.0  
**Last Updated**: September 2026  
**Prepared For**: Development Team  
**Prepared By**: Product Management Team

# 🎨 HouseHive Design System & Frontend Master Plan

**Version 1.0 — The complete visual, layout, and interaction blueprint**

---

## 1. Design Vision — "Calm. Warm. Alive."

Before any pixel, we define three pillars that govern every decision:

| Pillar | Meaning | How it shows up |
|--------|---------|-----------------|
| **Calm** | Nothing shouts. Content leads, chrome recedes. | Generous whitespace, muted neutrals, one accent color doing the talking |
| **Warm** | A home platform should *feel* like home, not a database. | Honey-gold brand color, soft rounded geometry, human microcopy |
| **Alive** | The interface responds like it has physics. | Every action gets feedback — springs, ripples, cross-fades, real motion |

**North Star Reference**: What Apple's design language would feel like if it were a friendly neighborhood rental platform — precise but never cold.

**The One Rule**: *If an element doesn't help a user find a home or fill a home, it doesn't belong on screen.*

---

## 2. Brand Identity

### Logo Concept
- **Mark**: A minimal house silhouette where the roofline forms a honeycomb hexagon — one shape, two meanings (house + hive)
- **Wordmark**: "HouseHive" in Plus Jakarta Sans Bold, the "o" optionally replaced by the hexagon mark
- **Usage**: Mark alone at small sizes (nav, favicon, app icon), full lockup on landing and auth screens

### Illustration Style
- Thin-line, 2px stroke, single-hue icons (Lucide set)
- Empty states use custom line illustrations with one honey-gold accent element per scene
- No clipart, no stock photos of smiling people — properties ARE the hero imagery

### Voice & Microcopy
- Friendly, direct, zero jargon: "Find your next home" not "Search rental inventory"
- Empty states talk like a person: "No saved homes yet — tap the heart on any listing and it'll wait for you here."
- Success moments celebrate: "Your home is live! 🎉"

---

## 3. Design Tokens (The Single Source of Truth)

All design decisions are encoded as tokens. Every screen below consumes only these values.

### 3.1 Color System

**Brand — Honey (primary accent)**

```
honey-50   #FFF8ED   → tinted backgrounds, hover washes
honey-100  #FFEFD4   → selected chip backgrounds
honey-200  #FEDCAA   → badge fills
honey-300  #FDBF78   → borders on emphasis
honey-400  #FBA03C   → large text accents
honey-500  #F97F14   → PRIMARY (buttons, links, focus)
honey-600  #EA670C   → hover state
honey-700  #C2510C   → pressed state
```

**Neutral — Ink (warm-gray, not cold-gray)**

```
ink-900    #1C1917   → primary text
ink-700    #44403C   → secondary text
ink-500    #78716C   → tertiary text, placeholders
ink-300    #D6D3D1   → borders, dividers
ink-200    #E7E5E4   → disabled fills
ink-100    #F5F5F4   → sunken surfaces
ink-50     #FAFAF9   → page background
white      #FFFFFF   → raised surfaces (cards, sheets)
```

**Semantic**

| Token | Value | Use |
|-------|-------|-----|
| `verified` | `#059669` | Verified badge, success |
| `verified-soft` | `#ECFDF5` | Badge background |
| `danger` | `#E11D48` | Errors, destructive |
| `info` | `#2563EB` | Informational toasts |
| `featured` | `honey-500` | Premium/featured ring |

**Dark Mode** (full parity, toggle in nav, follows system preference)

```
--bg-page:      #0F0E0D   (not pure black — warm dark)
--bg-raised:    #1C1917
--bg-sunken:    #171514
--text-primary: #F5F5F4
--text-secondary: #A8A29E
--border:       #292524
--honey stays, brightened to honey-400 for contrast
Verified green brightened to #34D399
```

### 3.2 Typography

**Stack** (both free, Google Fonts, self-hostable):

| Role | Font | Weights |
|------|------|---------|
| Display / Headings | **Plus Jakarta Sans** | 600, 700, 800 |
| Body / UI | **Inter** | 400, 500, 600 |
| Prices / Stats | Inter with `font-feature-settings: "tnum"` | 600 |

**Fluid Type Scale** (scales with viewport, clamped):

| Token | Size (min → max) | Weight | Use |
|-------|------------------|--------|-----|
| `display-xl` | 44 → 72px | 800 | Landing hero only |
| `display-l` | 36 → 48px | 700 | Section headlines |
| `h1` | 28 → 34px | 700 | Page titles |
| `h2` | 22 → 26px | 700 | Section headers |
| `h3` | 18 → 20px | 600 | Card group titles |
| `body-l` | 17px | 400 | Property descriptions |
| `body` | 15px | 400 | Default |
| `caption` | 13px | 500 | Meta, helper text |
| `micro` | 11px | 600 | Uppercase eyebrows, badges |

**Rules**: Line-height 1.5 body / 1.15 display. Max 68ch reading width. Prices always tabular numbers so digits don't jitter when values change.

### 3.3 Spacing, Grid & Radius

**Spacing scale** (4pt base): `4 · 8 · 12 · 16 · 20 · 24 · 32 · 40 · 48 · 64 · 80 · 96`

**Grid**:

| Viewport | Columns | Gutter | Content max-width |
|----------|---------|--------|-------------------|
| < 640px | 4 | 16px | fluid |
| 640–1023px | 8 | 20px | fluid |
| ≥ 1024px | 12 | 24px | 1280px |
| ≥ 1536px | 12 | 32px | 1440px |

**Radius scale**:

```
r-sm  8px    → inputs, chips
r-md  12px   → small buttons, badges
r-lg  16px   → buttons, dropdowns
r-xl  20px   → cards
r-2xl 28px   → sheets, modals, hero search
r-full       → pills, avatars, map markers
```

### 3.4 Elevation & Depth (Apple-style soft shadows)

Never pure black — always ink-tinted, always layered:

```css
--shadow-xs:  0 1px 2px rgba(28,25,23,.05);
--shadow-sm:  0 1px 3px rgba(28,25,23,.08), 0 1px 2px rgba(28,25,23,.04);
--shadow-md:  0 4px 12px rgba(28,25,23,.08), 0 2px 4px rgba(28,25,23,.04);
--shadow-lg:  0 12px 32px rgba(28,25,23,.12), 0 4px 8px rgba(28,25,23,.05);
--shadow-xl:  0 24px 64px rgba(28,25,23,.16);
--shadow-glow: 0 4px 16px rgba(249,127,20,.35);  /* primary button hover */
```

**Glass surfaces** (used sparingly — sticky nav, floating map UI, modals):

```css
--glass: rgba(255,255,255,.72) + backdrop-blur(20px) saturate(180%);
--glass-border: rgba(255,255,255,.5) top-edge highlight;
```

### 3.5 Motion Tokens

| Token | Duration | Easing | Use |
|-------|----------|--------|-----|
| `instant` | 100ms | ease-out | Color/hover swaps |
| `fast` | 200ms | `cubic-bezier(.25,1,.5,1)` | Chips, tooltips, buttons |
| `normal` | 300ms | `cubic-bezier(.25,1,.5,1)` | Cards, accordions |
| `smooth` | 450ms | `cubic-bezier(.32,.72,0,1)` | Sheets, drawers, page fades |
| `spring` | 500ms | `cubic-bezier(.34,1.4,.64,1)` | Playful pops — heart burst, badge unlock |
| `deliberate` | 700ms | ease-in-out | Hero elements, large reveals |

**Motion laws**:
1. Enter fast, exit faster
2. Nothing teleports — things slide/fade from where they came
3. `prefers-reduced-motion` → all durations collapse to 0ms, opacity fades only
4. Max 2 animated elements visible at once per viewport region

---

## 4. Core Component Library

### 4.1 Buttons

| Variant | Appearance | Use |
|---------|-----------|-----|
| Primary | Honey-500 fill, white text, `r-lg` | One per view max — the main action |
| Secondary | White fill, 1.5px ink-300 border | Secondary actions, filter panels |
| Ghost | Transparent, honey text | Inline actions, "View all" |
| Soft | Honey-50 fill, honey-700 text | Chips, toggles |
| Danger | Danger fill | Delete/deactivate |

**States**: default → hover (lift 1px + glow) → active (press scale .97 + honey-700) → focus (2px honey ring + 2px offset) → loading (spinner replaces label, width locked) → disabled (ink-200, no interaction).

**Sizes**: `sm` 36px / `md` 44px (default) / `lg` 52px (hero search, CTAs). All ≥44px touch target.

### 4.2 Property Card — *The Hero Component*

The single most-seen component. Spec it perfectly.

```
┌───────────────────────────────┐
│ ● ● ● ○                 ♡     │  ← dots = in-card gallery (swipe/tap),
│        [ 4:3 PHOTO ]          │     heart top-right, bursts on tap
│  ✦ VERIFIED          NEW      │  ← badges top-left, verified has
│                               │     animated shine sweep every 4s
├───────────────────────────────┤
│ ₹14,500 /mo                   │  ← price: 20px, weight 700, tabular
│ 2BHK Apartment · Kandari      │  ← title: 16px semibold
│ 📍 Near Civil Line, Solapur   │  ← location: caption, ink-500
│                               │
│ 🛏 2  🚿 2  📐 850 sqft  3rd  │  ← meta row: icon + value, caption
│ ┌AC┐ ┌Parking┐ ┌Lift┐ +4      │  ← amenity chips, max 3 + "+n"
└───────────────────────────────┘
```

- Container: white, `r-xl`, `shadow-sm`, 1px ink-100 border
- **Hover** (desktop): translateY(-4px), shadow blooms to `lg`, photo scales 1.05 (600ms), border tints honey-300, "View home →" hint fades in bottom-right
- **Press** (mobile): scale .98 + shadow-xs — feels physical
- **Verified listings**: 2px green ring around image + badge; the badge has a diagonal light-sweep animation
- Entire card is one tap target; heart and dots stop propagation

### 4.3 Search Bar (Hero) — *The Signature Element*

```
┌──────────────────────────────────────────────────┐
│  🔍  Where do you want to live?   │ Rent ▾ │ Go │
└──────────────────────────────────────────────────┘
```

- Pill shape, `r-2xl`, white on glass, `shadow-lg`
- On focus: **expands upward** into a panel with rent slider, BHK selector, property-type chips (450ms `smooth`)
- As-you-type location autocomplete with area + city results, keyboard navigable
- Recent searches + "Popular in [city]" shown when empty

### 4.4 Filter System (two patterns)

**A. Filter Chips Row** (always visible above results):
`[ Rent ▾ ] [ BHK ▾ ] [ Type ▾ ] [ Verified only ◉ ] [ More filters ]`
Active filters turn honey-soft with a clear "×". Count badge on "More" when hidden filters active.

**B. Filter Drawer** (mobile: bottom sheet / desktop: left rail):
- Rent: **dual-thumb slider** with live price labels that follow thumbs
- BHK: segmented control `1 2 3 4+`
- Amenities: checkable chips
- "Family / Bachelor friendly" toggle
- Sticky footer: `[ Reset ]  [ Show 128 homes ]` — button label shows live result count

### 4.5 Map Markers (custom-built — this is a differentiator)

| Element | Design |
|---------|--------|
| **Price marker** | Pill `[ ₹14.5k ]` white fill, ink text, `shadow-md`; tap → selected state scales up, turns honey fill with white text, card in list highlights simultaneously |
| **Verified marker** | Tiny green check-dot pinned to pill corner |
| **Cluster** | **Hexagon** (brand tie-in!) honey gradient, white count number; tap → smooth zoom-in with markers fanning out |
| **Hover** (desktop) | Marker lifts; mini-card (photo, price, beds) floats above, 150ms pop |

### 4.6 Forms & Inputs

- Floating-label pattern: label sits inside input, animates up + shrinks on focus/fill (200ms)
- Validation: never block-and-alert. Invalid field gets 1.5px danger border + caption slides in below (spring)
- OTP inputs: 6 separate boxes, auto-advance, paste-friendly, success state boxes flip green one-by-one
- Multi-step wizard errors: step indicator dot turns danger, never lose entered data

### 4.7 Feedback Components

| Component | Spec |
|-----------|------|
| **Toast** | Bottom-center (mobile) / top-right (desktop), glass surface, icon + message + optional action, auto-dismiss 4s with progress line, swipe-to-dismiss |
| **Skeletons** | Every loading surface has a gray shimmer skeleton matching final layout — cards, map, dashboard stats. Content cross-fades in |
| **Empty states** | Line illustration + one-line human message + one primary action button |
| **Confetti** | Listing goes live / verification approved → brief honey-gold confetti burst from center (canvas-confetti, ~1.5s, respects reduced-motion) |

### 4.8 Verified Badge (the trust asset — make it coveted)

```
   ╭──────────────────╮
   │ ✓  VERIFIED HOME │   green-soft fill, verified-700 text,
   ╰──────────────────╯   shine-sweep animation, hexagon ✓ icon
```
Appears on card, detail hero, map marker, search chip. The animation is subtle repetition — never annoying, always noticed.

---

## 5. Screen-by-Screen Layout Blueprints

### 5.1 Landing Page (Guest)

```
┌─────────────────────────────────────────────────────────┐
│ ◆ HouseHive        Explore  Map  For Owners    [Log in] │ ← glass sticky nav,
├─────────────────────────────────────────────────────────┤   appears after 80px scroll
│                                                         │
│         YOUR NEXT HOME IS NEARBY.                       │ ← display-xl, ink-900
│         Verified houses across India's real cities.     │ ← body-l, ink-500
│                                                         │
│    ┌───────────────────────────────────────┐            │
│    │ 🔍 Where?  │ ₹ Rent ▾ │ 2BHK ▾ │  Go  │ ← hero search pill
│    └───────────────────────────────────────┘            │
│         Solapur · Kolhapur · Ranchi · Ujjain · +12      │ ← city chips
│                                                         │
│              ⌄ scroll to explore ⌄                       │ ← breathing indicator
│         [soft animated gradient mesh bg]                │
├─────────────────────────────────────────────────────────┤
│  ✓ Physically verified   ✓ No fake listings   ✓ Free to │
│                          search                          │ ← trust strip
├─────────────────────────────────────────────────────────┤
│  Homes people are loving right now              View →  │
│  ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐                    │
│  │card│ │card│ │card│ │card│ │card│   ←→ swipe          │ ← featured carousel,
│  └────┘ └────┘ └────┘ └────┘ └────┘                      auto-scroll, drag,
├─────────────────────────────────────────────────────────┤ peek next card
│  ┌───────────────────────────────────────────────┐      │
│  │  SEE THE MAP. PICK YOUR AREA.                 │      │
│  │  [ Live map preview with pulsing markers ]    │ ←→  │ ← interactive map
│  │         [ Explore on Map ]                    │      │ preview + CTA
│  └───────────────────────────────────────────────┘      │
├─────────────────────────────────────────────────────────┤
│  HOW IT WORKS                                           │
│   [icon]        [icon]          [icon]                  │
│   Search        Visit            Move in                │ ← 3 steps, icons
│   by map        with unlock      with confidence        draw themselves on
│                 contact          (verified homes)        scroll
├─────────────────────────────────────────────────────────┤
│  FINDING HOMES IN                                       │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐                    │
│  │city 1│ │city 2│ │city 3│ │city 4│  + grid            │ ← city tiles with
│  └──────┘ └──────┘ └──────┘ └──────┘                     listing counts
├─────────────────────────────────────────────────────────┤
│  ┌─────────────────┐   ┌─────────────────┐              │
│  │  I HAVE A HOME  │   │  I NEED A HOME  │              │ ← dual CTA split
│  │  List it free → │   │  Start free →   │              │ cards, slight tilt
│  └─────────────────┘   └─────────────────┘              │ on hover
├─────────────────────────────────────────────────────────┤
│  ❤ What tenants say  (horizontal testimonial scroll)    │
├─────────────────────────────────────────────────────────┤
│  Footer: 4 cols · cities · links · app badges · ©       │
└─────────────────────────────────────────────────────────┘
```

**Behavior details**:
- Hero background: extremely subtle animated gradient mesh (honey → rose → sky at 8% opacity), slow 20s drift
- Nav starts transparent over hero, gains glass background on scroll (300ms)
- Sections fade-and-rise 24px into view via IntersectionObserver, staggered 80ms per card
- City chips trigger a live-search redirect

---

### 5.2 Explore — Search Results (Split View) — *the workhorse screen*

```
Desktop (≥1024px):
┌───────────────────────────────────────────────────────────────┐
│ ◆ HouseHive   [🔍 area, city          ] [Save search] [♡] [⚙] │
├──────────────────────────────┬────────────────────────────────┤
│ 128 homes · Solapur          │                                │
│ [chips: rent ▾ bhk ▾ ⬤ verif]│                                │
│                              │                                │
│ ┌──────────────────────┐     │      ◉₹12k  ◉₹15k   ⬡7       │
│ │ property card        │     │                                │
│ └──────────────────────┘     │         ◉₹8.5k        ◉₹22k   │
│ ┌──────────────────────┐     │                                │
│ │ property card        │     │    ← 60/40 split map          │
│ └──────────────────────┘     │      stays sticky              │
│ ┌──────────────────────┐     │      drag divider              │
│ │ property card        │     │                                │
│ └──────────────────────┘     │                                │
│        ····· infinite ·····  │                                │
│ [Back to top ↑] floating btn │                                │
└──────────────────────────────┴────────────────────────────────┘

Mobile: results as vertical card feed → [ Map ] floating pill button
bottom-right → full-screen map mode with draggable bottom sheet
holding compact horizontal-scroll cards (Snapchat-style).
```

**The killer interaction — list ↔ map sync**:
- Hover a card → its map marker pulses & enlarges
- Tap a marker → list auto-scrolls that card into view with a honey-soft highlight that fades
- Filters update both panes simultaneously with a 200ms cross-fade (never a hard reload)

---

### 5.3 Full Map Exploration Mode ("empty map" experience)

```
┌───────────────────────────────────────────────────────────────┐
│ ┌─────────────────────────┐   [List ⇄ Map toggle]  [⚙] [⚙]   │
│ │ 🔍 Search area or city  │                                  │
│ └─────────────────────────┘         legend:  ●₹<10k  ●₹10-20k│
│                                              ●₹20k+  ⬡cluster │
│                                                               │
│                     ◉₹12k      ◉₹18k                          │
│                                                               │
│        ⬡24                    ◉₹9k                           │
│                ◉₹15k ✓ver                                     │
│                              ⬡11          ◉₏₏₏              │
│                                                                  │
│        [ ⊕ Draw search area ]  [ 🎯 Near me ]                  │
│                                                               │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ [ ▣ compact card ][ ▣ card ][ ▣ card ] ← horizontal snap  │ │ ← draggable
│ │                            swipe for more · 24 in this area│ │  bottom sheet
│ └───────────────────────────────────────────────────────────┘ │    (3 heights)
└───────────────────────────────────────────────────────────────┘
```

- Draw tool lets users lasso an area → markers re-filter live
- Markers cluster by hexagons at low zoom; cluster tap = smooth animated zoom + fan-out
- Selecting a marker pops an in-map mini-card (photo, price, beds, ♥) → "View details" expands to full page

---

### 5.4 Property Detail Page

```
┌───────────────────────────────────────────────────────────────┐
│ ← Back                        ♡ Save    ⤴ Share               │
├───────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────┬────┬────┐                    │
│  │                             │ 🖼  │ 🖼  │  ← hero gallery   │
│  │      MAIN PHOTO 16:10       ├────┴────┤    main + thumbs,  │
│  │   (in-card swipe on mobile) │  🖼  🖼  │    "View all 12"   │
│  └────────────────────────────┴─────────┘                    │
├───────────────────────────────────────────────────────────────┤
│ ✓ VERIFIED HOME                       Listed 2 days ago      │
│ ₹14,500 /month · ₹29,000 deposit                              │
│ 2BHK Apartment — Kandari, Solapur                              │
│ 🛏 2 bed 🚿 2 bath 📐 850 sqft 🏢 3rd of 4 floors ⚡Semi-furn  │
├───────────────────────────────────────────────────────────────┤
│  Overview │ Amenities │ Location │ Owner                       │ ← sticky sub-nav,
├───────────────────────────────┬───────────────────────────────┤   scroll-spy active
│  DESCRIPTION                  │  ┌───────────────────────┐    │   state
│  Bright east-facing 2BHK...   │  │  ABOUT THE OWNER     │    │
│                               │  │  ○ avatar  Ramesh S. │    │
│  WHAT'S INCLUDED               │  │  ★ member since '23  │    │
│  ┌AC┐┌Parking┐┌Lift┐┌Water 24h┐│  │  2 other listings    │    │
│  ┌Power backup┐┌Security┐ +3   │  └───────────────────────┘    │
│                               │                               │
│  LOCATION                     │  ┌───────────────────────┐    │
│  [ Google Maps iframe embed ] │  │  📞 CONTACT UNLOCKED? │    │
│  Nearby (auto):               │  │                       │    │
│  🏥 Hospital 0.8km            │  │  [ 🔓 Unlock Owner's  │    │ ← THE moment.
│  🏫 School   1.2km            │   │    Number ]           │    │
│  🚂 Station  2.1km            │  │  We'll notify the     │    │
│                               │  │  owner you're         │    │
│  SIMILAR HOMES →              │  │  interested.          │    │
│  [card][card][card]           │  └───────────────────────┘    │
│                               │  (desktop: sticky column;     │
│                               │   mobile: sticky bottom bar)  │
└───────────────────────────────┴───────────────────────────────┘
```

**The Contact Unlock** — our signature trust interaction:
1. User taps "Unlock Owner's Number"
2. Button morphs into a scramble-decode animation where digits shuffle and settle into the real number (600ms, spring) — feels like cracking a safe, in a delightful way
3. Two buttons materialize: **[ 💬 WhatsApp ]** (pre-filled message: "Hi, I'm interested in your 2BHK in Kandari listed on HouseHive") and **[ 📅 Request Visit ]** (opens calendar sheet with owner's available slots)
4. Number stays blurred in the raw page copy always — unlock state is per-user session, logged as an "interest lead" for the owner

**Gallery**: swipe with momentum, pinch-zoom lightbox on tap, counter "3 / 12", thumbnails on desktop.

---

### 5.5 Auth Screens

```
┌───────────────────────────────┬───────────────────────────────┐
│                               │                               │
│   ◆ HouseHive                 │   [photo of a real verified   │
│                               │    home — full-bleed, subtle  │
│   Welcome back.               │    Ken Burns zoom]            │
│   Log in to continue.         │                               │
│                               │   ✓ 12,400 verified homes     │
│   ┌ phone / email ─────────┐  │   ✓ 32 cities and growing     │
│   ┌ password ─────────────┘  │                               │
│   [        Log in         ]  │                               │
│                               │                               │
│   — or —                      │                               │
│   [ G  Continue with Google ] │                               │
│                               │                               │
│   New here? Create account →  │                               │
└───────────────────────────────┴───────────────────────────────┘
Mobile: single column, illustration replaces photo panel
```

**Role selection at signup** (critical moment — make it delightful):

```
        What brings you here?

   ┌──────────────┐   ┌──────────────┐
   │     🏠       │   │     🔑       │
   │  I OWN a    │   │  I NEED a   │
   │   home      │   │   home      │
   │             │   │             │
   │ List it,    │   │ Search,     │
   │ find        │   │ visit,      │
   │ tenants     │   │ move in     │
   └──────────────┘   └──────────────┘
```
Cards are large tap targets; selected card lifts + honey border, then a springy "Nice! Let's set you up →" button slides up.

---

### 5.6 Owner Dashboard

```
┌──────────┬────────────────────────────────────────────────────┐
│          │  Good evening, Ramesh 👋            [ + List Home ] │
│  ◆ HH    │                                                    │
│  ───────  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐      │
│  📊 Home  │  │ 1,247  │ │   38   │ │   12   │ │  89%   │      │
│  🏠 Listed│  │ views  │ │ inquiry│ │ visits │ │ resp.  │      │
│  💬 Inquir│  │ this wk│ │ this wk│ │ booked │ │ rate   │      │
│  📅 Visits│  └────────┘ └────────┘ └────────┘ └────────┘      │
│  ✅ Verify│   ↑ numbers count-up on load (800ms, stagger)      │
│  💳 Plan  │                                                    │
│  ⚙ Settngs│  YOUR LISTINGS                     [Active ▾]     │
│          │  ┌────────────────────────────────────────────┐    │
│  ───────  │  │ [img] ₹14,500 · 2BHK Kandari   ✅Verified  │    │
│  Ramesh S │  │       342 views · 8 inquiries               │    │
│  ○ avatar │  │       [Edit] [Share] [⋯]                    │    │
│  Log out  │  ├────────────────────────────────────────────┤    │
│          │  │ [img] ₹9,000 · 1RK Prabhat  ⚠ Under review  │    │
│          │  │       120 views · 2 inquiries                │    │
│          │  │       [Edit] [Share] [⋯]                     │    │
│          │  └────────────────────────────────────────────┘    │
│          │                                                    │
│          │  PENDING ACTIONS                                   │
│          │  ┌ 3 new visit requests need your response → ┐     │
│          │  ┌ Your Kandari listing is ready for          │     │
│          │  │ verification — book a visit →              ┐     │
└──────────┴────────────────────────────────────────────────────┘
Mobile: sidebar collapses to bottom nav: Home · Listings · Inquiries · Visits · Me
```

---

### 5.7 Property Upload Wizard — *with Live Preview (standout feature)*

```
┌──────────────────────────────────────────────────────────────┐
│ ← Save & exit        LIST YOUR HOME              [Step 3/5]  │
│  ●───────●───────○───────○───────○                          │
│  Basic   Photos  Details  Amenities  Publish                 │
├──────────────────────────────────────────┬──────────────────┤
│  WHAT KIND OF HOME IS IT?                │  LIVE PREVIEW    │
│                                          │  (always visible,│
│  [ Apartment ] [ House ] [ PG ] [ Room ] │  updates as you  │
│                                          │   type — users   │
│  HOW MANY BEDROOMS?                      │  see their real  │
│  [ 1 ] [ 2 ] [ 3 ] [ 4+ ]                │  listing card    │
│                                          │  build itself)   │
│  WHAT'S THE RENT?                        │                  │
│  ₹ [ 14,500 ] / month                    │  ┌────────────┐  │
│  Security deposit  ₹ [ 29,000 ]          │  │ your photo  │  │
│                                          │  │ or elegant  │  │
│  WHERE IS IT?                            │  │ placeholder │  │
│  [ 🔍 Start typing area/street…  ]       │  ├────────────┤  │
│  [ 📍 Pin exact location on map ]        │  │ ₹14,500/mo │  │
│      (opens map, draggable pin)          │  │ 2BHK·Kandari│ │
│                                          │  └────────────┘  │
│                          [ ← Back ] [ Continue → ]           │
└──────────────────────────────────────────┴──────────────────┘
```

- Progress dots fill with spring animation; leaving mid-way auto-saves a draft
- **Photo step**: large drag-drop zone with animated dashed border, multi-upload with per-image progress rings, drag-to-reorder, "Set as cover" on first image, per-photo blur (hide a number plate, etc.)
- **Amenities step**: chips grouped (Comfort / Safety / Essentials) with select-all shortcuts
- **Publish step**: summary checklist + visibility preview ("How tenants will see you") then a confetti moment on going live

---

### 5.8 Verification Flow (Owner → "Get Verified")

```
│  STAND OUT WITH THE VERIFIED BADGE                          │
│                                                             │
│  ✦ [Badge demo with shine animation]                        │
│                                                             │
│  1  You book a visit        ₹499 one-time                  │
│  2  Our team photographs & inspects the home                │
│  3  Badge goes live within 48 hours                         │
│                                                             │
│  [ See what we check ✓ ]        [ Book Verification → ]     │
│                                                             │
│  After booking → status tracker:                            │
│  ● Booked → ● Team assigned → ● Visit done → ● Badge live   │
│  (each state change fires a notification + dashboard pulse) │
```

---

### 5.9 Tenant Dashboard / Saved

```
│  Hi Priya 👋                                                │
│                                                             │
│  ♡ SAVED HOMES (6)          🔔 2 price drops · 1 new        │
│  [card] [card] [card] [card] …                              │
│                                                             │
│  📅 UPCOMING VISITS                                         │
│  ┌─────────────────────────────────────┐                    │
│  │ SUN, 15 JUN · 11:00 AM              │                    │
│  │ 2BHK Kandari · with Ramesh S.       │                    │
│  │ [Directions] [Message] [Reschedule] │                    │
│  └─────────────────────────────────────┘                    │
│                                                             │
│  🔍 YOUR SEARCHES                                           │
│  [ 2BHK · Solapur · under ₹15k ]  [ 1RK near station ]      │
│  ← one-tap re-run, shows new-results count                  │
```

### 5.10 Messages

Chat interface: owner/tenant conversations, initiated automatically on contact-unlock or visit-request. Bubbles (mine honey, theirs white/ink-100), visit-request cards rendered inline as rich messages with Accept/Reschedule/Decline actions, timestamps + read receipts, image sharing. Mobile: full-screen, keyboard-aware.

### 5.11 Admin Console

Data-dense but calm: left icon rail, full-width tables (never cramped cards), sticky column headers, command-style global search (⌘K everywhere), and the **Verification Queue** as the star screen:

```
│  VERIFICATION QUEUE (14 pending)                            │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ LISTING #4821 · Kandari, Solapur · booked 12 Jun       │ │
│  │ ┌──────────────────────┬──────────────────────┐        │ │
│  │ │ OWNER PHOTOS (6)     │ FIELD PHOTOS (8)      │       │ │
│  │ │ [img][img][img]…     │ [img][img][img]…      │       │ │
│  │ └──────────────────────┴──────────────────────┘        │ │
│  │ Checklist: ☑ address match  ☑ rent match                │ │
│  │            ☑ condition match  ☐ owner ID verified       │ │
│  │ Notes: [____________________]                           │ │
│  │         [ ✗ Reject with reason ]  [ ✓ Approve Badge ]   │ │
│  └────────────────────────────────────────────────────────┘ │
```
Approve → fires badge + confetti notification to owner. Analytics use Chart.js: clean line/bar charts on ink-50 cards, honey accent series.

---

## 6. Interaction & Animation Catalog

Every animation, in one place:

| # | Interaction | Motion spec |
|---|-------------|-------------|
| 1 | Page transitions | View Transitions API cross-fade + 8px rise, 300ms `smooth` |
| 2 | Card hover | Lift 4px + shadow bloom + image zoom, 600ms |
| 3 | Heart/save | Scale punch 1→1.3→1 + tiny particle burst, spring |
| 4 | Verified badge | Diagonal shine sweep every 4s (2s pass), infinite, subtle |
| 5 | Contact unlock | Number digits scramble-decode settle, 600ms spring |
| 6 | Stat counters | Count-up 0→value with ease-out, 800ms, stagger 100ms |
| 7 | Map cluster tap | Zoom + markers fan-out from hexagon origin, 450ms |
| 8 | List↔map sync | Paired pulse ring on marker (2 pulses) + card highlight fade |
| 9 | Bottom sheets | Drag with real finger-follow physics; snap to 3 detents |
| 10 | Filter apply | Results cross-fade (200ms out/in), result count morphs |
| 11 | Wizard progress | Dots fill with spring; step content slides 24px horizontally |
| 12 | Scroll reveals | Sections rise 24px + fade, 450ms, staggered per child |
| 13 | Photo galleries | Momentum swipe, lightbox scale-from-origin |
| 14 | Toasts | Slide up + settle bounce; progress bar linear 4s |
| 15 | Dark mode toggle | Circle-wipe transition from toggle origin, 500ms |
| 16 | Skeleton→content | Shimmer skeleton cross-fades to real content, 300ms |
| 17 | Empty→filled (wizard) | Live preview card updates with a soft 300ms swap |
| 18 | OTP success | Boxes flip green sequentially, 100ms stagger |
| 19 | Publish confetti | Honey-gold burst, 1.5s, center origin |
| 20 | ⌘K palette | Backdrop blur-in + panel rise 12px, 250ms |

**Command palette (⌘K)** — desktop power feature: search properties, jump to saved homes, navigate dashboard, toggle dark mode. Slides down from nav with blur backdrop. This single feature makes the product feel "high-end tech."

---

## 7. Information Architecture & Navigation Hierarchy

```
GUEST
├── Landing
├── Explore (list / split / full-map)
│     └── Property Detail (public view, contact locked)
└── Auth (login · signup · role select · OTP · forgot)

TENANT (after login)
├── Explore (unlocked: save, unlock contact, request visit)
├── Saved Homes
├── My Searches
├── My Visits (upcoming / past / actions)
├── Messages
└── Profile & Settings

OWNER
├── Dashboard (stats + pending actions)
├── My Listings → New/Edit Wizard → Verification flow
├── Inquiries (interest leads + questions)
├── Visit Manager (calendar + accept/decline)
├── Messages
└── Settings (+ subscription/plan)

ADMIN
├── Overview (platform analytics)
├── Verification Queue ★
├── Listings (moderation, featured, takedown)
├── Users & Roles
├── Leads & Activity
├── Payments & Plans
└── Cities / Areas management
```

**Navigation rules**:
- Guests see everything except actions — this drives signup conversion naturally (save a home → "Create a free account to keep it")
- Role determines the nav shell; users with both roles switch via profile menu
- Mobile: 5-slot bottom bar with active-pill indicator (background slides between tabs, 300ms)

---

## 8. Responsive Strategy

| Pattern | Mobile (<640) | Tablet (640–1023) | Desktop (≥1024) |
|---------|--------------|-------------------|-----------------|
| Nav | Bottom bar (logged-in) / hamburger + sticky search (guest) | Collapsed top nav | Full top nav + ⌘K |
| Property cards | Full-width, stacked meta | 2-col grid | 3-col grid (list pane: 1-col wide cards) |
| Search results | Feed → map via floating toggle | Toggle, map full-screen | 60/40 sticky split with drag divider |
| Filters | Bottom sheet, 92% height | Bottom sheet | Left rail / top drawer |
| Detail page | Sticky bottom action bar | Sticky bottom action bar | Right sticky contact column |
| Upload wizard | Single column, preview collapses to accordion | Preview as top banner | Side-by-side with live preview |
| Dashboards | Bottom nav + stacked stats (2×2 grid) | Same + visible sidebar at 1024 | Full sidebar layout |
| Maps | Full-screen + drag sheet (3 detents) | Same | Inline split or full-screen |

**Mobile-first laws**: 44px minimum targets, thumb-zone for primary actions (bottom), no hover-dependent features, momentum scrolling everywhere, address bar collision safe (100dvh, safe-area insets).

---

## 9. Recommended Free Frontend Stack (Laravel-native, zero license cost)

| Layer | Tool | Why |
|-------|------|-----|
| Styling | **Tailwind CSS** | Consumes our design tokens directly; consistency by construction |
| Interactivity | **Alpine.js** + **Livewire** | Ships with the Laravel ecosystem; dropdowns, sheets, filters, toggles with zero build complexity |
| Icons | **Lucide** | 1500+ consistent 2px-stroke icons, free |
| Fonts | **Inter + Plus Jakarta Sans** (Google Fonts, self-hosted) | Modern, free, tabular numerals support |
| Carousels/Galleries | **Swiper** (MIT) | Best-in-class touch galleries with momentum |
| Interactive map | **Leaflet + OpenStreetMap tiles** | Completely free markers/clusters/custom hexagons — no map billing ever |
| Detail-page location | **Google Maps iframe embed** (free) | As required, embed after unlock |
| Charts (admin) | **Chart.js** | Clean, lightweight |
| Confetti | **canvas-confetti** | 3kb of pure delight |
| Scroll animations | IntersectionObserver + Alpine transitions | No heavy animation framework needed for 95% of motion |
| Advanced motion (optional) | **Motion One / GSAP** (free) | Only if hero-level choreography is demanded later |

Everything above is open-source/free — no subscription, no per-load pricing, no vendor lock-in.

---

## 10. Design QA Checklist (Definition of "Done, Beautifully")

**Tokens & consistency**
- [ ] Only token values used — no magic hex/px anywhere
- [ ] Dark mode passes every screen (screenshot review per page)
- [ ] Typography scale respected; prices render in tabular figures

**Layout**
- [ ] Every screen tested at 390 / 768 / 1280 / 1440 widths
- [ ] No horizontal scroll, no CLS (aspect-ratio boxes on all media)
- [ ] Sticky elements never overlap content; safe-area insets respected

**Interaction**
- [ ] Every button has hover + active + focus + disabled + loading states
- [ ] Every list has loading (skeleton), empty, error, and success states
- [ ] `prefers-reduced-motion` honored globally
- [ ] List↔map sync verified with slow 3G throttling

**Accessibility**
- [ ] WCAG AA contrast in both themes (honey-on-white verified)
- [ ] Visible focus rings, keyboard path through every flow (search → filter → card → detail → unlock)
- [ ] Semantic landmarks, alt text, aria-labels on icon buttons

**Trust moments**
- [ ] Verified badge renders identically in: card, detail, map, search chip
- [ ] Contact number never present in page source before unlock
- [ ] Unlock, visit-request, and publish all give celebratory feedback

---

## 11. Build Order Suggestion (Design → Code)

1. **Week 1** — Tokens + component library (buttons, cards, inputs, badges) with a living style-guide page
2. **Week 2** — Landing page + auth flow + navigation shells
3. **Week 3** — Explore screen: filters, list view, cards feed
4. **Week 4** — Map mode: markers, clusters, sync, bottom sheets
5. **Week 5** — Property detail + gallery + contact unlock + visit request
6. **Week 6** — Owner wizard with live preview + owner dashboard
7. **Week 7** — Messages, tenant dashboard, notifications
8. **Week 8** — Admin console + verification queue + analytics
9. **Week 9** — Dark mode pass, animation polish, accessibility pass
10. **Week 10** — Performance pass (skeletons, lazy media, code discipline) + full QA checklist run

---

> **The one-sentence test for every screen**: *A first-time visitor in Solapur on a ₹8,000 phone should be able to go from "where do I even start" to "I'm talking to the owner" without a single moment of confusion — and they should smile at least twice on the way.*

**Document Version**: 1.0 · Design Master Plan
**Companion to**: HouseHive Requirements Document v1.0